MacFormat 1994 September

home *** CD-ROM | disk | FTP | other *** search

/ MacFormat 1994 September / macformat-004.iso / Shareware City / Developers / Mac F2C 1.0 / Mac F2C READ ME < prev next >

Wrap

Text File | 1994-06-11 | 19.2 KB | 450 lines | [TEXT/ttxt]

Mac F2C -- A FORTRAN-to-C compiler for the Macintosh ****************************************************** F2C core ©1989-1994 AT&T Bell Laboratories and Bellcore Macintosh Interface ©1994 Igor Mikolic-Torreira This software is freeware: it may be used and copied freely so long as the copyright notices and associated documentation remain attached. CONTENTS ******** A. Mac F2C REQUIREMENTS B. WHAT IS INCLUDED C. IF YOU ARE NOT USING THINK C VERSION 7 D. INSTALLING Mac F2C E. BRINGING THE LIBRARIES UP-TO-DATE F. VERIFYING CORRECT OPERATION OF Mac F2C G. TRANSLATING FORTRAN PROGRAMS H. USING C CODE PRODUCED BY MAC F2C I. KNOWN PROBLEMS J. COMPATIBILITY WITH UNIX F2C K. BUG REPORTS AND OTHER COMMENTS L. LICENSE AND OTHER ANNOYING LEGAL STUFF A. Mac F2C REQUIREMENTS ************************ (1) A 68020 or better (2) System 7.0 or better (3) At least 1 MB of available RAM (2 MB is preferred) B. WHAT IS INCLUDED ******************** The Mac F2C distribution set contains the following items: (1) "READ ME" -- A copy of this Read Me message. (2) "Mac F2C" -- the Fortran-to-C compiler. (3) "Mac F2C Libraries" -- a folder containing the libraries required to support programs translated by F2C. libF77 provides the floating- point support; libI77a and libI77b provide the integer and I/O support. These libraries need to be placed where THINK C can find them and brought up-to-date. See the sections below on installing Mac F2C and on bringing libraries up-to-date. (4) "For 'Standard Libraries'" -- a folder containing versions of the ANSI and unix libraries distributed with THINK C modified to work with Mac F2C output. These libraries should be placed in the "Standard Libraries" folder located in the folder that contains the THINK Project Manager; see the section on installing Mac F2C. These libraries also need to be brought up-to-date; see the section below on bringing libraries up-to-date. (5) "For '(Project Models)'" -- a folder containing a model Mac F2C project. If you have THINK C v7.0 or better, the contents of this folder should be placed in the "(Project Models)" folder located in the folder that contains the THINK Project Manager; see the section on installing Mac F2C. See the section below on using C code produced by Mac F2C for information on how to use the model Mac F2C project. (6) "AT&T Report 149.ps" -- a postscript file containing AT&T Computing Science Technical Report No. 149. This report provides very detailed documentation on F2C, the UNIX program on which is the core of Mac F2C. Consider it your compiler and language reference manual. All users should printout and read this report. (7) "Test Project ƒ" -- a folder containing a test FORTRAN program and the C output produced by Mac F2C. It also contains a complete project to compile and run that program. See the section below on verifying correct operation. (8) "For non THINK v7 users" -- a text file containing additional instructions for users who are using earlier versions of THINK C or other compilers. All the project files included in this distribution have been made using THINK C version 7.0.2. This file provides guidance on how to create equivalent project files using earlier versions of THINK C. It also includes guidance for users who are not using Symantec's THINK C compiler (e.g., users of CodeWarrior or MPW). C. IF YOU ARE NOT USING THINK C VERSION 7 ****************************************** If you have an older version of THINK C, you cannot use the project files I have shipped. You must build your own versions from scratch. I have included additional instructions in the separate file "For non THINK v7 users". This also includes some general guidance for users of other compilers (e.g., CodeWarrior or MPW), but because I do not own either of these, I can only provide general guidance. If you are a THINK version 6 user, let me point out that there is a FREE updater from Symantec that will update your project manager, debugger, and compilers to version 7.0 (there is also a free 7.0 --> 7.0.2 updater). This updater does _not_ include the Universal Headers, Visual Architect, or TCL 2.0. The updater can be found in most Macintosh-oriented archive sites. D. INSTALLING Mac F2C ********************** For easiest and smoothest operation, the support libraries should be installed where the THINK C compiler can find them easily. If you are using THINK version 7, the model project also needs to go in particular location. I recommend you install Mac F2C as follows: (1) The folder "For 'Standard Libraries'" contains two THINK project files: "ANSI F2C" and "unix F2C". Drag both of these files -- not the folder itself -- to the "Standard Libraries" folder located in the same folder as the THINK Project Manager application. (2) Drag the _entire_ folder "Mac F2C Libraries" to the folder that contains the THINK Project Manager application. (3) The folder "For '(Project Models)'" contains a model project folder called "Mac F2C Project". If you are using THINK version 7 or better, drag the folder "Mac F2C Project" to the "(Project Models)" folder located in the same folder as the THINK Project Manager application. If you do not have THINK version 7 or better, see the section below on using C code produced by Mac F2C for information on how to use the model Mac F2C project. E. BRINGING THE LIBRARIES UP-TO-DATE ************************************* If you are using THINK C version 7.0 or better, the libraries are easily brought up to date using the following steps. If you are using an earlier version of THINK C or another compiler, please refer to the special instructions in the file "For non THINK v7 users". To bring the Mac F2C libraries up-to-date follow this algorithm: FOR the project files: (1) "ANSI F2C" in the "Standard Libraries" folder (2) "unix F2C" in the "Standard Libraries" folder (3) "libI77a" in the "Mac F2C Libraries" folder (4) "libI77b" in the "Mac F2C Libraries" folder (5) "libF77" in the "Mac F2C Libraries" folder REPEAT the following steps: (a) Double-click on the project file. (b) In the THINK Project Manager's "Source" menu, select the "Make" command. (c) Uncheck the "Quick Scan" check-box. (d) Click on the "Use Disk" button. (e) Click on the "Make" button. END REPEAT F. VERIFYING CORRECT OPERATION OF Mac F2C ****************************************** The folder "Test Project ƒ" contains the following files: (1) "test.f" -- a sample FORTRAN program. (2) "test.c (sample)" -- what you should get when you translate the sample FORTRAN code files. (3) "main.c" -- the main program required to run programs produced by with Mac F2C. (4) "f2c.h" -- an include file required to compile programs produced by Mac F2C. (5) "Test.π" -- a THINK C v 7.0 project to run the sample program. This will serve as a model for how to compile, link, and run programs translated by F2C. Note that code produced by F2C must be compiled with 4-byte integers, 8-byte doubles, native floating-point format, far code, and far data. (6) "Test.π Contents" - a text file describing the contents of Test.π Translate the sample FORTRAN program "Test.f" simply by dragging it onto Mac F2C. Do not change any of the options (use "Factory Defaults"). Once you have done this you can compare it with "Test.c (sample)" file to verify that you got the same thing. If so, double click on the THINK project "test.π" and follow the same steps outlined in the "Bringing Libraries Up-To-Date" section to bring the test project up-to-date. Run it to verify correct operation. G. TRANSLATING FORTRAN PROGRAMS ******************************** You can use Mac F2C to translate FORTRAN to C using three methods: (a) Start up Mac F2C and select the corresponding command in the File menu. (b) Drag-&-Drop a bunch of FORTRAN files onto Mac F2C. (c) Use a scripting language (e.g., AppleScript) to send Mac F2C either an open command or a translate command. FORTRAN files must be TEXT files and *must* end in ".f" or ".F" (sorry, but the ending is determined by the unix F2C kernel -- it rejects files handed to it with any other endings). The Options menu lets you control the various translation and code generation options. You can also set the creator type for the output files. If you check the "Make these the new defaults" box before clicking the "OK" button, your option selections will be saved in a Preference file and used again the next time you start Mac F2C. If you do not understand what an option means, check the balloon help. The help balloons provide more detailed explanations of what each option means. They also explain why dimmed options are not available and what you can do to make them available. H. USING C CODE PRODUCED BY MAC F2C ************************************ The C code produced by Mac F2C has the following compile and link requirements: - the header file "f2c.h" - the libraries libI77a, libI77b, libF77, ANSI F2C, and unix F2C - 4-byte integers - 8-byte doubles - native floating-point format - far code - far data In addition, if you compile a stand-alone FORTRAN program (vice only some FORTRAN subroutines) you must include "main.c" in your project. This is because the original main routine in the FORTRAN program becomes a function that is called by main.c. In addition, main.c performs a series of initializations (primarily related to error catching) prior to executing the main FORTRAN program. The model project provided ("Mac F2C Project") is a folder that contains everything you need to compile and run code produced by Mac F2C. This folder has a copy of main.c, f2c.h, and a project file that includes the appropriate libraries and option settings. If you have THINK C version 7.0 or better, simply create a new project by using the "New" command in the THINK Project Manager's "File" menu and selecting "Mac F2C Project" as the model for the new project. Add your code files as appropriate, bring it up-to-date (you may need to use the "Make" command and the "Use Disk" option the first time), and run. If you have an earlier version of THINK C, first replace the project file provided in "Mac F2C Project" with one made with your version of THINK (I have included a list of the project contents for your convenience -- see the additional instructions in the file "For non THINK v7 users" if you have trouble doing this). Do not include any objects at this time. To start a new project, duplicate the entire "Mac F2C Project" folder, change the names of files and folders as appropriate, add your code files, and bring everything up-to-date. If you compile a FORTRAN subroutine or function that you want to call from a C program, look at the output C code to see the appropriate calling protocol. You may or may not need to include the F2C support libraries (libF77, libI77a, and libI77b). In rare cases, you may also need to copy some of the initialization code from "main.c" to your calling program. As noted above, code produced by Mac F2C *MUST* be compiled with 4-byte integers. This requirement cannot be relaxed. The other requirements (8-byte doubles, native floating-point format, far data, and far code) can sometimes be relaxed: - IF you do not use doubles in any situation where their size relative to reals matters (e.g., if you do not use doubles in equivalence and common statements), then your code probably does not require 8-byte doubles. You need to verify this on a case- by-case basis. This requirement exists because Mac F2C follows FORTRAN sizing rules when compiling FORTRAN code: sizeof(real) == sizeof(integer) and sizeof(double) == 2*sizeof(real). FORTRAN real is compiled as C float and FORTRAN double as C double, so doubles have to be 8-bytes long for equivalence and common statements to be properly aligned. There are a few other cases where the size of double variables matters; see AT&T Computing Science Technical Report No. 149 (included with Mac F2C) for a detailed discussion. - IF you compile your program with the option "Local variables are automatic" and you do not have large static data structures, you *might* not need "Far Data". You need to verify this on a case- by-case basis. Mac F2C creates large static data structures for I/O. If you create local variables in the global area (static vice automatic) or if you have other static data, you will almost certainly require "Far Data". The I/O data structures can be large enough that you may require "Far Data" for that reason alone. - IF your program is not very large and doesn't have a large number of subroutines, you probably will not need "Far Code". You need to verify this on a case-by-case basis. Mac F2C tends to produced redundant copies of utility code (especially code for performing array indexing). It can also produce large numbers of auxiliary functions. The result is that "Far Code" is often required. Compile first with "Far Code", then check the code size and jump table to see if you can relax this requirement. - IF your program will NOT be compiled under Symantec C++ (i.e., you chose K&R C or ANSI C output vice C++ output), you do not need native floating-point format. The native floating-point format option is selected only to guarantee compatibility with the Symantec C++ compiler should you chose to produce C++ code from the FORTRAN code. If you change the "8-byte doubles", "native floating-point format", "Far Code", or "Far Data" options, remember to also change them in all the libraries, specifically "libI77a", "libI77b", "libF77", "ANSI F2C", and "unix F2C". I urge all users to read the enclosed AT&T Computing Science Technical Report No. 149. Consider it your compiler and language reference manual. You can print the report by downloading it to any PostScript printer. You can use Apple's LaserWriter Utility application to do this or you can use any of the many equivalent utilities. I. KNOWN PROBLEMS ****************** There are a series of problems in Mac F2C that arise because the original UNIX version of F2C (a stand-alone program) is incorporated as a subroutine. The original UNIX F2C is designed to compile one file and quit, so lots of bugs such as memory leaks and dangling open files don't show up -- all memory is released and files are automatically closed when the program quits. In Mac F2C, the original F2C program has been turned into a subroutine which can be called several times -- and each time the leaked memory is lost to future iterations. I have fixed the dangling open file bugs in F2C, but not the memory leaks. This means that you can easily run out of memory if you translate more than about a dozen FORTRAN files at a shot (fewer if they are big or complicated). The work-around is to translate a few files at a time, quit and re-start Mac F2C, and then do a few more. You can also give Mac F2C a bigger memory allocation. I know this is less than satisfactory, but the memory leaks are too hard to fix. Sorry, but I had a bad enough time tracking down all the files that the original UNIX F2C left open. It was even harder to figure out how to close them without completely re-writing large portions of unix F2C! J. COMPATIBILITY WITH UNIX F2C ******************************* This version of Mac F2C is based on the unix version as of 4 April 1994. The unix version is maintained and updated on a semi- regular basis. I plan to update Mac F2C about once a year to incorporate all changes that have been made to the unix version during the past year. I may release interim versions at shorter intervals as required to fix significant bugs. K. BUG REPORTS AND OTHER COMMENTS ********************************** My name is Igor Mikolic-Torreira and I can be reached at igormt@alumni.caltech.edu. If you find Mac F2C useful, please drop me a note. If you really think it is the most useful thing in the whole world and worth its weight in gold, please donate that amount of gold to your favorite charity ;) If you find any bugs or would like to request a particular feature, let me know. I will try to fix interface bugs or at least provide work-arounds promptly. I will forward compiler bugs to AT&T. If you believe you have a code generation bug, _please_ send me a sample of the FORTRAN code that produces the problem. L. LICENSE AND OTHER ANNOYING LEGAL STUFF ****************************************** The compiler engine of Mac F2C is based on the unix version of F2C and is Copyright 1990, 1993, 1994 by AT&T Bell Laboratories and Bellcore. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that the copyright notice and this permission notice and warranty disclaimer appear in supporting documentation, and that the names of AT&T Bell Laboratories or Bellcore or any of their entities not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. AT&T and Bellcore disclaim all warranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall AT&T or Bellcore be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software. The Macintosh interface portion of Mac F2C was written and is Copyright 1994 by Igor Mikolic-Torreira. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that the copyright notice and this permission notice and warranty disclaimer appear in supporting documentation, and that the name of Igor Mikolic-Torreira not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. Igor Mikolic-Torreira disclaims all warranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall Igor Mikolic-Torreira be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.